Summary

• Added lightweight architecture guardrails in tests/ArchitectureGuardrails.Tests.ps1 so key infrastructure seams and layering expectations stay enforced by automated tests instead of convention alone.
• Expanded plan.md with the next architecture follow-up slices and recorded tests/ArchitectureGuardrails.Tests.ps1 as the current host for these checks.
• This change was needed to make recent maintainability improvements harder to regress accidentally, especially around self-update execution, thin public command orchestration, and centralized project.json persistence.
• Follow-up reference: architecture-guardrail follow-up captured in plan.md.

Affected area

• nova CLI or command routing
• Public PowerShell cmdlet behavior
• Scaffolding or project.json handling
• Build, test, analyzer, coverage, or CI helper flow
• Package, raw upload, or package metadata workflow
• Publish, release, semantic-release, or GitHub Actions automation
• Self-update or notification preference behavior
• Contributor documentation (README.md, CONTRIBUTING.md, repository workflow docs)
• End-user docs (docs/*.html)
• Command help (docs/NovaModuleTools/en-US/*.md)
• src/resources/example/
• Dependency or manifest changes (package.json, workflow dependencies, release tooling)
• Security-sensitive change
• Documentation-only change
• Other

Other affected area details:

• Architecture guardrails and maintainability enforcement in tests/ArchitectureGuardrails.Tests.ps1

Review guidance

• Start with tests/ArchitectureGuardrails.Tests.ps1.
• Focus first on the new guardrails that protect:
  • direct Update-Module usage staying behind Invoke-NovaModuleUpdateCommand
  • public command files using only their approved Nova helper surface via AST-backed allowlists
  • project.json writes staying limited to Write-ProjectJsonData and its known callers
• Then review plan.md for the recorded follow-up plan and the updated examples of guardrails worth extending later.
• Primary files changed:
  • tests/ArchitectureGuardrails.Tests.ps1
  • plan.md
• Trade-off: the public-command helper rule is intentionally strict. When a public command legitimately adds or removes Nova helper calls, the allowlist in tests/ArchitectureGuardrails.Tests.ps1 must be updated alongside that change.

Validation

• Invoke-NovaBuild
• Test-NovaBuild
• ./scripts/build/Invoke-ScriptAnalyzerCI.ps1
• ./scripts/build/ci/Invoke-NovaModuleToolsCI.ps1
• Targeted Nova workflow validated (% nova build, % nova test, % nova merge, % nova deploy,
  % nova publish,
  % nova release, % nova update, % nova notification, or % nova init as relevant)
• Docs/example only; executable validation not needed

Validation notes:

Focused guardrail validation:
- pwsh -NoLogo -NoProfile -Command 'Invoke-Pester ./tests/ArchitectureGuardrails.Tests.ps1 -Output Detailed'
  Result: 7/7 tests passed.

Broader targeted validation completed during the architecture-guardrail work:
- UpdateNotification.Tests.ps1
- NovaCommandModel.BumpAndCli.Tests.ps1
- NovaCommandModel.ReleasePublish.Tests.ps1
- CoverageGaps.ReleaseInternals.Tests.ps1
- CoverageGaps.Tests.ps1
  Result: 197/197 tests passed.

Additional targeted validation after the stricter public-command allowlist was introduced:
- NovaCommandModel.Tests.ps1
- NovaCommandModel.ReleasePublish.Tests.ps1
- NovaCommandModel.BumpAndCli.Tests.ps1
- UpdateNotification.Tests.ps1
  Result: 163/163 tests passed.

Full repository validation completed during the change:
- pwsh -NoLogo -NoProfile -File ./run.ps1
  Result: PSScriptAnalyzer: no findings. Discovery found 561 tests. Tests Passed: 561, Failed: 0.

Diff hygiene:
- git --no-pager diff --check
  Result: clean.

Maintainability safeguards:
- CodeScene pre-commit safeguard: passed
- Code Health review for tests/ArchitectureGuardrails.Tests.ps1: 10.0

The template-specific boxes above remain unchecked because this change was validated through focused architecture suites and the repository quality flow (`run.ps1`) rather than by running those exact individual template commands in this final step.

Documentation and release follow-up

• README.md reviewed and updated if contributor workflow, architecture, CI, release, or automation changed
• CONTRIBUTING.md reviewed and updated if contribution expectations or review guidance changed
• CHANGELOG.md reviewed and updated if the change matters to users, maintainers, or contributors
• docs/NovaModuleTools/en-US/ help updated if a public command or CLI behavior changed
• docs/*.html updated if end-user workflows or examples changed
• src/resources/example/ reviewed and updated if the real-world project layout, package model, or upload workflow
  changed
• No documentation, changelog, or example updates were needed

Maintainability, compatibility, and risk

• Code Health / maintainability impact considered
• No breaking change
• Breaking change
• Security-sensitive change
• CI, workflow, or release-pipeline impact
• Dependency-review impact

Risk, rollout, or rollback notes:

Compatibility impact is low because the change adds tests and planning guidance only; it does not alter exported command behavior.

Rollback is straightforward:
- revert the new guardrails in tests/ArchitectureGuardrails.Tests.ps1
- revert the architecture follow-up notes in plan.md

Main maintainer follow-up:
- keep the public-command helper allowlist in sync when legitimate helper usage changes in src/public/*.ps1
- extend the guardrail suite incrementally instead of adding broad brittle restrictions